Running scripts on devices

Depending on the Absolute product licenses associated with your account, the Absolute Reach feature may not be available.

You can use the Absolute Reach® feature to upload your own script to the Secure Endpoint Console or select a script from the Absolute Reach Script Library and submit a request to run the script on your Windows or Mac devices. The next time an eligible targeted device connects to the Absolute Monitoring Center The server responsible for maintaining two-way communication with a device's Persistence agent, to initiate self-healing if the Secure Endpoint Agent is removed or tampered with, and to send device data and receive instructions., the device's Secure Endpoint Agent downloads the script to a startup folder, validates the script signature, and runs the script on the device from this location. Once the request is complete, the agent deletes the script from the startup folder.

If you want to collect user input that you can review in the Secure Endpoint Console, we recommend that you use a Send Message request instead of a script. If you use a script, the Custom Device Fields may fail to be populated with the users' responses.

You can submit a Run Script request from the Devices page or a device's Device Details page. You can also select devices in a device group, device group folder, or device report and submit a request for all selected devices. Alternatively, if you want to run a script on a large number of devices at one time, you can upload a file of device identifiers and submit a single Run Script request.

Absolute Reach is supported on Windows and Mac devices with an active Secure Endpoint Agent that is regularly connecting to the Absolute Monitoring Center.

It is not supported on the following devices:

To submit Run Script requests, your user role must be granted the Run permission for Reach Script. All Administrator roles and the Security Power User role are granted this permission by default.

To upload a script and use it in a Run Script request, your user role must be granted the Manage permission for Reach Script. The System Administrator and the Security Administrator roles are granted this permission by default.

To view a Run Script request's status in Action Requests, your user role needs to be granted the View permission for Reach Script. All Administrator roles and the Security Power User role are granted this permission by default.

The following practices ensure that the Reach script produces the desired results before you use Absolute Reach to deploy a script across your fleet of devices:

  • Add error handling to your PowerShell and Bash scripts to help troubleshoot any issues that may arise. Script return codes show in Action Requests and Event History.
  • Before you upload a PowerShell script, review the PowerShell guidelines pertaining to the Absolute schema.
  • In the Secure Endpoint Console, use the Run Script option to deploy the script on a small subset of test devices and observe the results.

To submit a Run Script request:

  1. Log in to the Secure Endpoint Console as a user with the Run permission for Reach Script.

  2. Do one of the following:

    On the device's Device Details page, click Run script.

    1. From the navigation bar, open a page that supports the Run Script action. For example, open the All Devices page in the Devices area or open the Makes and Models report.
    2. In the work area, use the search field or filters to find the applicable devices.

    3. In the results grid, select each device you want to include in the request. To select all devices, select the Select All checkbox in the result grid header. To select consecutive devices, select the first device and then hold down the Shift key and select the last device. You can select up to 350,000 devices. To remove all selections, click Clear all.

    4. Click Run script.

    Alternatively, you can upload a file of device identifiers and submit a request.

    If there are no Windows or Mac devices selected, a message shows. Click to close the dialog.

  3. Add a script to your request by doing one of the following:

    1. The list of scripts is pre-filtered based on whether Windows or Mac devices are selected. Enter part of the name or description of the script that you want to run in Search Scripts. Click Absolute or Custom to limit the search results. Search results update dynamically as you type.

      If the eligibility check takes more than 10 seconds, the scripts aren't filtered by device type.

    2. Click the script that you want to run.
    3. [Optional] At the top of the dialog, click Run script - <date> and enter a request name that will help you identify and track this request in Action Requests.
    4. [Optional] Click Add description (optional) and enter a description for the request.
    5. If you selected both Windows and Mac devices, but only want to run the script on Windows or Mac devices, clear the checkbox beside Windows or Mac.

    1. Click Create Script.

      The Create Script option is available only if you are logged in as a user with the Manage permission for Reach Script.

    2. [Optional] At the top of the dialog, click Run script - <date> and enter a request name that will help you identify and track this request in Action Requests.
    3. [Optional] Click Add description (optional) and enter a description for the request.

    4. If you do not want to be able to use the script for a future request, clear Save to Custom library.

      If Save to Custom library is selected, any PowerShell Parameters, Bash Parameters, and Advanced Configuration Options you set in the following steps are saved with the script in the script library. If you upload both a PowerShell and a Bash script, they are saved together.

    5. Verify that your script meets the following requirements:

      • The script is in one of the following formats:

        • PowerShell script (.ps1): for Windows devices

          If the script contains Unicode characters, use UTF-8 encoding and include the Byte Order Mark (BOM).

          We recommend that all PowerShell scripts use UTF-8 encoding and include the BOM.

        • Bash script (.sh): for Mac devices
      • The script doesn't exceed 1468 KB in size
      • The file name doesn't contain any spaces

    6. Do one or both of the following:

      1. Click Upload PowerShell Script.

        Upload PowerShell Script is available only if you selected Windows devices.

      2. Navigate to the location of the PowerShell script file (.ps1) that you want to upload and click Open.

        If the script isn't signed, you see a message that Absolute will sign the script.

        If the script is signed, the signature format is verified. If the format is invalid signature, you see an error message. Verify the signature and reupload the script. The signature will be validated at the device when the script is used in a Run Script request.

        To validate the script's signature at the device, the device must be running Secure Endpoint Agent version 9.0 or higher.

      1. Click Upload Bash Script.

        Upload Bash Script is available only if you selected Mac devices.

      2. Navigate to the location of the Bash script file (.sh) that you want to upload and click Open.

  4. Set the script configurations by doing one or both of the following, depending on the type of script selected or uploaded:

    1. In the Windows Devices section, click View Script to see a preview of the script.

      You can't edit the text in the preview box. If you need to edit a custom script, open the script file on your computer and edit it. You can replace the original uploaded script with the edited script by clicking Upload PowerShell Script and selecting the edited script file.

    2. If the Script Variables section shows, enter a value in any field marked required. For all other fields, enter a value, if applicable. Required fields have a thick left border .

    3. If you want to specify one or more parameters for your script, enter them in the PowerShell Parameters field.

      The PowerShell Parameters field is not validated for correct syntax. Ensure that you enter the parameters correctly.

    4. Set the Advanced Configuration Options for the script:

      Configuration Options
      Rights

      Select one of the following options:

      • Run with system account rights: run the script using the rights associated with the local system account

        Ensure that you select this option if the PowerShell script references Absolute .dll files, as non-system accounts do not have access to these files.

      • Run with logged in user rights: run the script using the rights of the logged in user

        Ensure that you select this option if the PowerShell script requires access to the device user's data or input from the device user (such as acknowledgment of a license agreement).
      Display Mode

      Select one of the following options (if available):

      • Hidden: run the script in the background so it is not visible to the user
      • Maximized: show the Windows PowerShell dialog on the device
      • Minimized: minimize the Windows PowerShell dialog to the Windows taskbar
      Run Condition

      Select one of the following options:

      • No user is signed in: run the script only when no user is logged in
      • User is or isn't signed in: run the script regardless of whether a user is logged in
      • User is signed in: run the script only when a user is logged in
      Maximum Run Time

      Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

      To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
      Run 32-bit version If you want to use the 32-bit version of PowerShell (x86) to run the script on 64-bit Windows devices, select the checkbox. If you leave the checkbox cleared, the 64-bit version of PowerShell is used to run the script on these devices.

    1. In the Mac Devices section, click View Script to see a preview of the script.

      You can't edit the text in the preview box. If you need to edit a custom script, open the script file on your computer and edit it. You can replace the original uploaded script with the edited script by clicking Upload Bash Script and selecting the edited script file.

    2. If you want to specify one or more parameters for your script, enter them in the Bash Parameters field.

      The Bash Parameters field is not validated for correct syntax. Ensure that you enter the parameters correctly.

    3. Set the Advanced Configuration Options for the script:

      Configuration Options
      Rights

      Select one of the following options:

      • Run with system account rights: run the script using the rights associated with the local system account
      • Run with logged in user rights: run the script using the rights of the logged in user
      Display Mode This field is unavailable for Bash Scripts
      Run Condition This field is unavailable for Bash Scripts
      Maximum Run Time

      Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

      To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
  5. Click Run on x devices.

The request is submitted and a Script requested event is logged to Event History. You can track the progress of the Run Script request in Action Requests.

The request is deployed to each device on its next successful connection to the Absolute Monitoring Center, which is typically within a few minutes for Absolute Resilience accounts, or within 15 minutes for Absolute Control accounts, assuming the devices are online. If the request requires dual approval, the request remains in the Pending Approval section in Action Requests. The action isn't sent to the device until the request is approved. After the device receives the request, it is placed in the device's job queue. In Action Requests, the device's action status is set to Processing.

After the script runs on the device, the action status is set to Succeeded. If the script fails to complete for any reason, such as ineligibility or exceeding the Maximum Run Time, the action status is set to Failed and the reason is displayed in Action > Status details.

If you need to cancel a Run Script request after you created it, you can attempt to cancel the request on devices if the request is still pending.

  • To cancel all pending Run Script requests for a single device, go to the device's Device Details page. Learn more
  • To cancel a single pending request for one or more devices, go to Action Requests. Learn more